// Copyright (c) 2010, Anthony Cassidy
// All rights reserved.
// 
// Redistribution and use in source and binary forms, with or without modification, are 
// permitted provided that the following conditions are met:
// 
//     * Redistributions of source code must retain the above copyright notice, this list 
//         of conditions and the following disclaimer.
//     * Redistributions in binary form must reproduce the above copyright notice, this 
//         list of conditions and the following disclaimer in the documentation and/or 
//         other materials provided with the distribution.
//     * Neither the name of the AntsAdventureGameCreator nor the names of its contributors 
//         may be used to endorse or promote products derived from this software without 
//         specific prior written permission.
// 
// 
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY 
// EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 
// OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT 
// SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
// CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 
// THE POSSIBILITY OF SUCH DAMAGE.

/*!
@page Example9
<h1>Example 9 - Adding Resource Rooms</h1>
<h2>Summary</h2>
Currently, only single rooms have been mentioned.
But what if there are multiple rooms, and they need to share resources.

This can be done using Resource Rooms.

Each room contains a list of other rooms which it uses as Resource Rooms.

The resources of these additional rooms are pulled
in to the inventory and object lists.

A Room specifies its resource rooms by three macros for declaration:
- 1) ROOMDECLARATION_WITH_CODES_AND_RESOURCE_ROOMS_BEGIN(roomName);
- 2) ROOMDECLARATION_WITH_CODES_AND_RESOURCE_ROOMS_ENTRY(resourceRoomName);
- 3) ROOMDECLARATION_WITH_CODES_AND_RESOURCE_ROOMS_END();
- 4) ROOMDECLARATION_FOR_CPP(roomName);

ResourceRooms are not nestable: That is, if room A contains an entry to room B,
and in roomB's declaration it contains an entry to room C, then room A would 
not contain a reference to room C.

When a Room is being used as a ResourceRoom, some of its event handlers 
are also called at the normal time.
- IEventHandlers::OnInitializeRoom() - this is called at the normal time. 
- IEventHandlers::OnExitRoom() - this is called at the normal time.
- IExtraEventHandlersForUseWithCodes::OnCommandLineExecuteWithCodes() - this is called at the normal time.

These handlers can be useful for placing global handlers.
<br>
For example, if a player contains a particular inventory item
then this item should be initialised to be in his inventory
when he walks into any room.
<br>
Another example is using one inventory item with another inventory item.
This can presumably be done in any room. Such a command is best handled
in the IExtraEventHandlersForUseWithCodes::OnCommandLineExecuteWithCodes() handler of a resource room that is
shared by all rooms.
<br>
Other handlers are not called for various reasons:
- IEventHandlers::OnEnterRoom() - is NOT called, as this exists for story telling, and presumably only one story per room is necessary.
- IEventHandlers::OnEveryTick() - is NOT called. This would not scale well.

One limitation of using Resource Rooms is
that when you use the DEF(), or INVDEF() or ANIMDEF() macros in a header, 
they use the line number to create a unique id.
As a result, if a cpp file contains the DEF(object1) on line 15,
and includes a header file which contains DEF(object2) on line 5,
then both items will be given the same id. This effectively makes
it impossible to use ids as a reliable way to identify objects. 
<br>
The currently recommended solution to this problem is to manually
make sure the DEF()s of a shared header do not use the same lines as a cpp.
For example, if you only had one shared header you could make all its xxDEF(object)
macros start from line 50, and have all the cpps start from near the top 
of the cpp file, and make sure they don't go past line 50.



@includelineno main9.cpp

<br>
*/

